plot3D (version 1.4)

plots with legend or colorkeys: Plots with legend or colorkeys outside of the plotting region

Description

legendplot, legendmatplot, legendhist and legendpairs create plots with a legend adjacent to it, using R's default plotting functions plot, matplot, hist and pairs.

colorkeyplot, colorkeymatplot, colorkeyhist and colorkeypairs create a plot with a colorkey adjacent to it.

createKey creates suitable colors for the color variables.

legend.plt and colorkey.plt are general functions that might also work with other plotting methods, and that add a legend or color key by changing the plt parameter.

legend.oma and colorkey.oma are general functions that might also work with other plotting methods, and that add a legend or color key by changing the oma parameter.

Usage

legendplot    (..., legend = list(), legend.side = 4, legend.cex = 1, legend.pars = NULL)  
legendmatplot (..., legend = list(), legend.side = 4, legend.cex = 1, legend.pars = NULL)  
legendhist    (..., legend = list(), legend.side = 4, legend.cex = 1, legend.pars = NULL)  
legendpairs   (..., legend = list(), legend.side = 4, legend.cex = 1, legend.pars = NULL)  
legend.plt (method = "plot", ..., legend = list(), legend.side = 4, legend.cex = 1, 
            legend.pars = NULL)  
legend.oma (method = "pairs", ..., legend = list(), legend.side = 4, legend.cex = 1, 
            legend.pars = NULL)  
colorkeyplot    (..., colorkey = list(), colorkey.side = 4)
colorkeymatplot (..., colorkey = list(), colorkey.side = 4)
colorkeyhist    (..., colorkey = list(), colorkey.side = 4)
colorkeypairs   (..., colorkey = list(), colorkey.side = 4)
colorkey.plt (method = "plot",..., colorkey = list(), colorkey.side = 4)
colorkey.oma (method = "pairs",..., colorkey = list(), colorkey.side = 4)
createKey (x, clim = NULL, col = NULL, NAcol = "black")

Value

The legend plotting functions return as invisible, a list that contains the plotting parameters for the regions of the legend and of the main plotting region, elements called plt.legend and plt.main. For the pairs method, the list returned contains the size of the outer margin instead, i.e. the oma parameter.

Arguments

method

A plotting method to which to add the legend or colorkey, such as plot, matplot, boxplot, ... Note that not all of R's plotting functions can be used.

...

Any argument passed to plot, matplot, hist or any other method.

colorkey.side, legend.side

On which side of the plot (1=bottom, 2=left, 3=top, 4=right) to put the legend or color key.

legend.cex

The expansion factor of the space around the legend.

legend.pars

A list that determines the size of the legend and of the main plotting region, as returned by any of the legend plotting functions. It should contain two vectors, one that sets the size of the plotting region called plt.main and one that sets the size of the legend, called plt.legend. The format of these vectors is as the parameter "plt". See last example.

colorkey

A list with arguments passed to function colkey.

legend

A list with arguments passed to function legend.

x

The variable for which the color key has to be created.

col

Colors to be used for the color key. If col is NULL, then a red-yellow-blue colorscheme (jet.col) will be used.

clim

The range of the color values, used in the color key.

NAcol

Color to be used for NA values.

Author

Karline Soetaert <[e-mail]>

Examples

# save plotting parameters
pm <- par(mfrow = c(2, 2))
pmar <- par(mar = c(5.1, 4.1, 4.1, 2.1))


# ============================================================================
#  Colorkey and legend added to simple plot
# ============================================================================

par(mfrow = c(2,1))
x <- seq(0, 2*pi, length.out = 30)
y <- sin(x)

# Note: this forgets the names of the x and y-variables.
colorkeyplot(x = x, y = y, col = createKey(y), pch = 18,
              main = "colorkeyplot with 'plot'", 
              colorkey = list(clim = range(y)))
abline (v = 4)
abline (h = 0.4)

legendplot(x = x, y = y, col = c("red", "blue")[(y > 0)+1], 
          main = "legendplot with 'plot'", pch = 18, 
          xlab = "x", ylab = "y", 
          legend = list(col = c("red","blue"), pch = 18, 
                          legend = c(">0", "<0")))
abline (v = pi)
abline (h = 0)

par(mfrow = c(1,1))
legendplot(x = x, y = y, col = c("red", "blue")[(y > 0)+1], 
          main = "legendplot with 'plot'", pch = 18,
          legend.side = 1, las = 1,
          legend = list(col = c("red","blue"), pch = 18, 
                      horiz = TRUE, legend = c(">0", "<0")))
abline (v = pi)
abline (h = 0)

# We do not label the y-axis, so the legend can be a 
# closer to the axis (legend.cex)
par(mfrow = c(1,1), mar = c(4,2,4,2))
legendplot(x = x, y = y, col = c("red", "blue")[(y > 0)+1], 
            main = "legendplot with 'plot'", pch = 18,
            legend.side = 2, legend.cex = 0.5, ylab = "",
            legend = list(col = c("red","blue"), pch = 18, 
                          horiz = FALSE, legend = c(">0", "<0")))

# Here we have a title with two lines, so the legend is put further away
# Also the legend is put near the bottom here.
legendplot(x = x, y = y, col = c("red", "blue")[(y > 0)+1], 
            main = "legendplot with 'plot'", pch = 18,
            legend.side = 2, legend.cex = 2, ylab = c("axis","on two lines"),
            legend = list(col = c("red","blue"), pch = 18, x = "bottomleft",
                          horiz = FALSE, legend = c(">0", "<0")))

# This works as ordinary legend function (except for the labeling of the axes)
par(mfrow = c(1,1), mar = c(4,4,2,2))
legendplot(x = x, y = y, col = c("red", "blue")[(y > 0)+1], 
            main = "legendplot with 'plot'", pch = 18,
            legend.side = 0,
            legend = list(col = c("red","blue"), pch = 18, x = "right",
                          horiz = TRUE, legend = c(">0", "<0")))

## =============================================================================
## ... added to a more complex plot
## =============================================================================

legend.plt(method = "points2D", x = x, y = y, colvar = y, 
           pch = c(18, 20)[(y > 0)+1], cex = 2, 
           colkey = list(side = 1, dist = -0.25, length = 0.4, shift = -0.15), 
           main = "legendplot with 'points2D'",
           legend = list(pch = c(18, 20), pt.cex = 2,
                         horiz = FALSE, legend = c(">0", "<0")))

# to use the image function with a color key - easier to do with image2D...
colorkey.plt(method = "image", x = 1:nrow(volcano), y = 1:ncol(volcano), 
             z = volcano, col = jet.col(100), 
             main = "colorkeyplot with 'image'",
             colorkey = list(col = jet.col(100), clim = range(volcano), clab = "m"))

## =============================================================================
## with matplot
## =============================================================================

# this is not a very instructive figure!  

lon <- Hypsometry$x           # Longitude
iy  <- seq(10, 180, by = 10)  # Index to latitudes where we want to see data
lat <- Hypsometry$y[iy]       # corresponding latitudes

Col <- createKey(iy)
colorkeymatplot(main = "matplot with color key",
                 xlab = "longitude", ylab = "heigh, m",
                 x = lon, y = Hypsometry$z[,iy], col = Col, type = "l", 
                 colorkey = list(clim = range(lat), clab = "latitude"))  

n <- 100
colorkey.plt(method = "pie", x = rep(1, n), labels = "", 
             col = rainbow(n), border = NA,
             main = "colorkeyplot with 'pie'", 
             colorkey = list(col = rainbow(n), clim = c(1,n)))

## =============================================================================
## A complex figure, consisting of overlays (based on example(boxplot))
## =============================================================================

plotit <- function(){
  boxplot(len ~ dose, data = ToothGrowth,
          boxwex = 0.25, at = 1:3 - 0.2,
          subset = supp == "VC", col = "yellow",
          main = "Guinea Pigs' Tooth Growth",
          xlab = "Vitamin C dose mg", ylab = "tooth length",
          xlim = c(0.5, 3.5), ylim = c(0, 35), yaxs = "i")
  
  boxplot(len ~ dose, data = ToothGrowth, add = TRUE,
          boxwex = 0.25, at = 1:3 + 0.2,
          subset = supp == "OJ", col = "orange")
}
legend.plt(method = "plotit", 
           legend = list(legend = c("Ascorbic acid", "Orange juice"),
                         fill = c("yellow", "orange")))

# All in one - putting legend on other side..
pm <- par(mar = c(4,3,4,2))
legend.plt(formula = len ~ dose:supp, data = ToothGrowth,
           boxwex = 0.5, col = c("orange", "yellow"),
           main = "Guinea Pigs' Tooth Growth",
           xlab = "Vitamin C dose mg", ylab = "tooth length",
           sep = ":", lex.order = TRUE, ylim = c(0, 35), yaxs = "i", 
           method = "boxplot", legend.side = 2, 
           legend = list(legend = c("Ascorbic acid", "Orange juice"),
                         fill = c("yellow", "orange")))
par(mar = pm)

## =============================================================================
## Nesting..
## =============================================================================

Fun1 <- function()
  legend.plt(x = 0, method = "plot", type = "n", xlab = "", ylab = "", axes = FALSE,
             frame.plot = TRUE, 
             legend = list(legend = 
            c("this can", "also be used", "to write text", "next to a plot")))

X <- legend.plt(method = "Fun1", legend.side = 1, 
              legend = list(legend = 
                     c("but also to put text", "below a plot"), 
                     horiz = TRUE, x = "left", box.col = "grey"))

print(X)
P <- par(plt = X$plt.legend, new = TRUE)  
plot.new()
legend("right", legend = "second legend")
par (plt = X$plt.main, new = TRUE)
plot.new()
legend("left", legend = "another legend")

## =============================================================================
## Pairs - note: this is not optimal 
## =============================================================================

legendpairs(iris, legend = list(legend = levels(iris$Species), cex = 0.5, col = 1:3, pch = 1), 
    legend.side = 4, col = (1:3)[iris$Species])

legendpairs( iris[1:4], main = "Anderson's Iris Data -- 3 species",
            pch = 21, bg = c("red", "green3", "blue")[unclass(iris$Species)],
            legend.side = 1,
            legend = list(levels(iris$Species), pt.bg = c("red", "green3", "blue"), 
                         pch = 21, title = "Species", horiz = TRUE))

# reset plotting parameters
par(mfrow = pm)
par(mar = pmar)

## Pairs with a color key

colorkeypairs(swiss[,c(1,4,5)], pch = 18, cex = 2, 
    col = createKey(swiss[,2]),
    colorkey=list(clim = range(swiss[,2]), clab = "Agriculture"))

## =============================================================================
## Aligning plots
## =============================================================================

par(mfrow = c(2,1))
AA <- legendplot(1:10, runif(10), xlab = "x", ylab = "y", pch= 18, 
      cex = 2, col = 1:10, 
      legend = list(col = 1:10, legend = 11111:11120, pch = 18, pt.cex = 2))

  legendplot(1:10, runif(10), xlab = "x", ylab = "y", pch= 18, 
      cex = 2, col = 1:10, legend.pars = AA,   # use par settings of previous plot
      legend = list(plot=FALSE))